@fabrika/builder 0.9.0-dev.13 → 0.9.0-dev.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (96) hide show
  1. package/BUILD-CONTRACT.md +9 -3
  2. package/README.md +39 -9
  3. package/cli/src/bin.ts +14 -1
  4. package/cli/src/build-review.ts +66 -0
  5. package/cli/src/build-status.ts +41 -3
  6. package/cli/src/catalog.ts +34 -2
  7. package/cli/src/commands/advance.ts +48 -6
  8. package/cli/src/commands/build.ts +152 -15
  9. package/cli/src/commands/design.ts +34 -0
  10. package/cli/src/commands/flows.ts +32 -0
  11. package/cli/src/commands/induce.ts +2 -2
  12. package/cli/src/commands/init.ts +7 -1
  13. package/cli/src/commands/next.ts +9 -2
  14. package/cli/src/context.ts +2 -1
  15. package/cli/src/contrast.ts +301 -0
  16. package/cli/src/daemon-client.ts +29 -3
  17. package/cli/src/design-review.ts +261 -0
  18. package/cli/src/flows.ts +162 -0
  19. package/cli/src/frontmatter.ts +32 -0
  20. package/cli/src/index.ts +10 -1
  21. package/cli/src/induce.ts +61 -3
  22. package/cli/src/issues.ts +15 -29
  23. package/cli/src/layout.ts +5 -2
  24. package/cli/src/packet.ts +36 -3
  25. package/cli/src/phase-state.ts +19 -1
  26. package/cli/src/verify.ts +50 -0
  27. package/daemon/src/handlers.ts +32 -6
  28. package/daemon/src/phases.ts +7 -109
  29. package/daemon/src/platform-source.ts +8 -0
  30. package/decisions/README.md +2 -2
  31. package/decisions/patterns/cf-contract-app.md +57 -0
  32. package/decisions/technologies/bun.md +2 -1
  33. package/decisions/technologies/cf-fabrika-contract.md +45 -0
  34. package/decisions/technologies/cloudflare.md +3 -1
  35. package/decisions/technologies/oblaka.md +1 -1
  36. package/decisions/technologies/opice.md +1 -1
  37. package/decisions/technologies/react.md +1 -1
  38. package/decisions/technologies/tailwind.md +5 -5
  39. package/decisions/technologies/zerops-fabrika-auth.md +1 -1
  40. package/decisions/technologies/zerops-platform.md +1 -1
  41. package/package.json +11 -8
  42. package/shared/approvals.ts +65 -0
  43. package/shared/derive.ts +189 -0
  44. package/shared/gate.ts +20 -0
  45. package/shared/index.ts +6 -1
  46. package/shared/phases.ts +22 -20
  47. package/skill/SKILL.md +25 -16
  48. package/skill/agents/build-orchestrator.md +28 -8
  49. package/skill/agents/flows-author.md +27 -13
  50. package/skill/agents/implementer.md +3 -1
  51. package/skill/agents/opice-skeleton-author.md +8 -7
  52. package/skill/gates/brief.jsx +26 -5
  53. package/skill/gates/review-grid.jsx +3 -8
  54. package/skill/gates/tech.jsx +3 -3
  55. package/stacks/README.md +8 -2
  56. package/stacks/cf-app.md +60 -0
  57. package/stacks/cf-fat.md +1 -0
  58. package/stacks/cf-internal-app.md +2 -2
  59. package/stacks/cf-lightweight.md +3 -2
  60. package/stacks/contember-app.md +1 -0
  61. package/stacks/content-site.md +1 -0
  62. package/stacks/zerops-app.md +1 -0
  63. package/types/cli/src/bin.d.ts +1 -1
  64. package/types/cli/src/build-review.d.ts +13 -0
  65. package/types/cli/src/build-status.d.ts +16 -1
  66. package/types/cli/src/catalog.d.ts +9 -0
  67. package/types/cli/src/commands/design.d.ts +1 -0
  68. package/types/cli/src/commands/flows.d.ts +1 -0
  69. package/types/cli/src/contrast.d.ts +59 -0
  70. package/types/cli/src/daemon-client.d.ts +13 -2
  71. package/types/cli/src/design-review.d.ts +54 -0
  72. package/types/cli/src/flows.d.ts +28 -0
  73. package/types/cli/src/frontmatter.d.ts +8 -0
  74. package/types/cli/src/index.d.ts +1 -1
  75. package/types/cli/src/induce.d.ts +3 -0
  76. package/types/cli/src/issues.d.ts +4 -0
  77. package/types/cli/src/packet.d.ts +9 -1
  78. package/types/cli/src/phase-state.d.ts +1 -1
  79. package/types/cli/src/verify.d.ts +18 -0
  80. package/types/daemon/src/phases.d.ts +4 -16
  81. package/types/daemon/src/platform-remote.d.ts +6 -2
  82. package/types/shared/approvals.d.ts +32 -0
  83. package/types/shared/derive.d.ts +41 -0
  84. package/types/shared/gate.d.ts +11 -0
  85. package/types/shared/index.d.ts +105 -65
  86. package/types/shared/phases.d.ts +7 -1
  87. package/ui/dist/assets/client.css +1 -1
  88. package/ui/dist/assets/client.vn7hykcn.js +120 -0
  89. package/ui/dist/index.html +1 -1
  90. package/cli/src/derive.ts +0 -105
  91. package/skill/gates/build.jsx +0 -20
  92. package/skill/gates/design.jsx +0 -22
  93. package/skill/gates/flows.jsx +0 -14
  94. package/skill/gates/vision.jsx +0 -27
  95. package/types/cli/src/derive.d.ts +0 -17
  96. package/ui/dist/assets/client.cemdw2n8.js +0 -214
package/BUILD-CONTRACT.md CHANGED
@@ -16,9 +16,15 @@ The builder CLI and dashboard must not import daemon implementation modules. The
16
16
 
17
17
  ## Phase model
18
18
 
19
- The ordered phases are intake, vision, flows, technology, design, skeletons, issues, and build. A phase is complete when every required output exists and its review gate, when present, has submitted and consumed feedback.
19
+ The ordered phases are intake, vision, flows, technology, skeletons, issues, and build. A phase is complete when every required output exists and its review gate, when present, has submitted and consumed feedback. Intake has no gate of its own: the vision gate reviews the brief together with the glossary and the principles, so the intent takes one review, not two in a row.
20
20
 
21
- The phase is always derived from application files and gate state. No mutable phase counter is authoritative.
21
+ Design is reviewed inside the build, on the running application: `induce` writes the design checkpoint `ISSUE-004` (`gate: design-checkpoint`, a name the removed design phase never used, so none of its old reviews counts), which depends on the foundation issues and which every feature issue depends on. `build done` on an issue with a `gate` records that gate's latest reviewed revision and its verdict as the issue's evidence, through `POST /api/session/:id/gate/:name/consume`; it refuses while the gate has no submitted feedback.
22
+
23
+ `design.md` may also list two or three theme variants (`variants: [<path>, …]`, each a stylesheet of `--fui-*` overrides). `design review` then shows each one side by side, with swatches, its overrides and its contrast, adds a required `variant` choice, and says which variant the imported stylesheet declares exactly. The preview shows only the imported stylesheet: the agent copies the chosen variant into it after the verdict and generates the view again. The variants are never imported by the application, and `build done` judges only the imported stylesheet.
24
+
25
+ The design checkpoint also carries a deterministic check, beside its advisory verdict. `.fabrika/architecture/design.md` names the theme stylesheet in its front matter (`stylesheet:`, repository-relative). `fabrika builder design review` and `build done` read that stylesheet's top-level `:root` and `:root[data-theme='dark']` custom properties over the `theme.css` of the `@fabrika/ui` that resolves from the stylesheet's directory, cascade them as the browser does (the kit's dark rule outranks an application's `:root`, and `!important` outranks both), and compute the WCAG 2 contrast of the pairs the kit's components draw: 4.5:1 for text, 3:1 for the focus ring. `build done` refuses a pair below that unless `--waive-contrast` is passed, and refuses while `design.md` names no stylesheet inside the repository; the evidence records the summary and any waiver. A pair the kit's own values already leave below AA, which the override does not lower, is shown and does not refuse. A pair is reported unchecked, never passed, when a colour cannot be read (a `var()` inside `color-mix()`, a translucent background) or when one of its tokens is also declared in a rule the check does not cascade (another selector, or inside `@media` or `@layer`). `--waive-contrast` is the driver's flag, like `advance --force`: the skill passes it only when the human accepts the listed pairs, and the evidence names each waived pair. A stylesheet from which `@fabrika/ui` does not resolve is a stack without the kit and is not checked.
26
+
27
+ The phase is always derived from application files, gate state and `.fabrika/approvals.json`. No mutable phase counter is authoritative. On success `advance` records, for a gated phase, the sha256 of every file the phase reads or produces and the gate revision whose review it approved (`approvals.json`, `version: 1`; `--force` marks the approval `waived` instead). The files are hashed when `advance` runs, so an edit made between the review and `advance` is approved with it. Once the file exists, a gated phase is complete only with an approval whose files are unchanged, plus, unless the approval is waived, a reviewed gate whose latest revision is the approved one. A stale phase is approved again only on a newer revision of its own gate. A file that does not parse, or of another version, is refused with a repair hint. The earliest gated phase whose files changed is current again, and its packet lists them on a `Stale:` line. The skeletons' approval covers only what they read, because the build fills in the test bodies. `init` writes an empty file for a new project. A project without the file is judged by its gate reviews alone: the first `next` or `advance` that reads its phase from the daemon writes the file and records the gated phases the daemon judged complete. Without the daemon such a project has no record of any review, so its first gated phase whose files exist stays current and `advance` refuses it until the gate is reviewed with the daemon running (or waived with `--force`, which writes the file with that gate alone).
22
28
 
23
29
  ## Application state
24
30
 
@@ -42,7 +48,7 @@ The installed console owns human application creation/selection and initial plac
42
48
  4. `gate wait` observes feedback without consuming it.
43
49
  5. `advance` validates outputs and consumes the latest feedback.
44
50
 
45
- Only `advance` consumes feedback. This keeps retries and re-opened gates pending until the agent explicitly advances.
51
+ `advance` consumes the current phase's own gate (`POST /api/session/:id/gate/:name/consume`), and re-opening a gate over pending feedback consumes that feedback and answers 409 with it. `gate wait` never consumes, so a retried wait sees the same feedback. A gate counts as reviewed once its latest revision's feedback was consumed, but in a project that keeps approvals only `advance` completes its phase; its verdict (the `verdict` answer) is recorded, and `advance` warns, without refusing, on anything but `Approve`.
46
52
 
47
53
  ## Release artifact
48
54
 
package/README.md CHANGED
@@ -2,18 +2,40 @@
2
2
 
3
3
  `@fabrika/builder` guides a coding agent from an initial application brief to a reviewed acceptance contract and an assisted implementation.
4
4
 
5
- The builder runs eight deterministic phases:
5
+ The builder runs seven deterministic phases:
6
6
 
7
- 1. intake
8
- 2. vision
7
+ 1. intake (no gate of its own)
8
+ 2. vision, whose gate reviews the brief with the glossary and principles
9
9
  3. flows
10
10
  4. technology
11
- 5. design
12
- 6. opice test skeletons
13
- 7. implementation issues
14
- 8. build
11
+ 5. opice test skeletons
12
+ 6. implementation issues
13
+ 7. build
15
14
 
16
- The current phase is derived from files in `.fabrika/`; it is not stored as a mutable counter. Review gates use a local dashboard with persistent annotations and responses.
15
+ Design is not a phase of its own. `induce` adds a design checkpoint issue, `ISSUE-004`, after the foundation issues and
16
+ before every feature: the agent themes the running application through the UI kit's `--fui-*` tokens, and the human
17
+ reviews it at the `design-checkpoint` gate in the live preview. `fabrika builder design review` generates that gate's view:
18
+ two or three theme variants side by side with a required choice, each with the WCAG contrast of the kit's text and focus
19
+ pairs under its override. `build done ISSUE-004` records the gate's
20
+ verdict, and refuses a pair below AA unless the reviewer waives it with `--waive-contrast`.
21
+
22
+ The current phase is derived from files in `.fabrika/`; it is not stored as a mutable counter. `advance` records the content of each approved phase's files, so a phase whose files change afterwards is current again. Review gates use a local dashboard with persistent annotations and responses.
23
+
24
+ ## Non-goals
25
+
26
+ The builder exists to take one brief for a new web application to a running application on the paved road: one UI kit,
27
+ the contract, the proxy and the checker ([ADR-0052](../../docs/decisions/0052-react-and-an-own-component-kit-for-application-spas.md)).
28
+ It does not grow into a general design tool. These are out of scope:
29
+
30
+ - **A node graph or node editor.** The phases are a fixed sequence, and the current one is derived from files and gate
31
+ state; nobody wires the steps by hand.
32
+ - **Multiplatform code generation** (native mobile or desktop UI) and **device simulators**. The paved road's
33
+ application is a web SPA on `@fabrika/ui`.
34
+ - **Editing controls in the dashboard,** such as token sliders or drag and drop. The dashboard edits nothing: a person
35
+ reviews there, sees the evidence, runs the connect and deploy actions, and asks for changes through the gate. The
36
+ agent makes the requested edits, and a person may still edit a file in their own editor.
37
+
38
+ A proposal for one of these needs a new ADR in `docs/decisions/` first, not a feature request.
17
39
 
18
40
  ## Usage
19
41
 
@@ -35,6 +57,9 @@ fabrika builder gate wait
35
57
  fabrika builder advance
36
58
  ```
37
59
 
60
+ A phase without a gate (intake, issues) completes as soon as its files exist: run `next` again instead of the gate and
61
+ `advance` steps. The vision gate reviews the brief that intake wrote.
62
+
38
63
  All commands:
39
64
 
40
65
  ```text
@@ -51,11 +76,16 @@ fabrika builder advance [--force]
51
76
  fabrika builder gate open <name> --view <file.jsx>
52
77
  fabrika builder gate wait [--gate <revision>] [--timeout <ms>]
53
78
  fabrika builder ensure-daemon
79
+ fabrika builder flows review
54
80
  fabrika builder induce [--force]
55
81
  fabrika builder build [--issue <ID>] [--assisted]
82
+ fabrika builder build done <ID> [--verify "<command>"]
83
+ fabrika builder build block <ID> --reason "<text>"
84
+ fabrika builder build status
85
+ fabrika builder build review
56
86
  ```
57
87
 
58
- Use `--profile cf-internal-app` for the full Buzola, Fabrika IAM, and Fabrika Control internal-app stack. The default is `cf-lightweight`.
88
+ The default profile is `zerops-app`. `--profile cf-app` selects the same paved road on Cloudflare: a contract application in one Durable Object per environment. The builder's `connect` and `deploy` work with a Zerops installation only, so a `cf-app` application is deployed by the installation's own Control. The other presets (`cf-lightweight`, `cf-fat`, `cf-internal-app`, `contember-app`, `content-site`) are kept for reference but are unsupported: they leave the contract, the proxy, the kit and the checker. `init`, the tech packet and the build brief warn when one is selected. `init` never replaces a project's profile; to move a project to a supported preset, change `profile` in `.fabrika/config.json` and revisit `.fabrika/architecture/tech.md`.
59
89
 
60
90
  Connected initialization uses `zerops-app` for a new project. A person approves the application and environment in the installed console; the local daemon receives a thirty-day app-scoped credential. The agent and application stay local. Deployment requires a clean, remotely available Git revision and runs through Control. `disconnect` removes the local key only; revoke server access in the console. See [the connected workflow](../../docs/reference/local-builder.md) for prerequisites, custody and recovery.
61
91
 
package/cli/src/bin.ts CHANGED
@@ -1,8 +1,11 @@
1
1
  #!/usr/bin/env bun
2
2
 
3
+ import { InvalidApprovalsError } from '../../shared/approvals'
3
4
  import { cmdAdvance } from './commands/advance'
4
5
  import { cmdBuild } from './commands/build'
6
+ import { cmdDesign } from './commands/design'
5
7
  import { cmdEnsureDaemon } from './commands/ensure-daemon'
8
+ import { cmdFlows } from './commands/flows'
6
9
  import { cmdGate } from './commands/gate'
7
10
  import { cmdInduce } from './commands/induce'
8
11
  import { cmdInit } from './commands/init'
@@ -32,8 +35,14 @@ Usage:
32
35
  fabrika builder gate open <name> --view <f.jsx> Push a canvas gate and open the dashboard
33
36
  fabrika builder gate wait [--gate <n>] [--timeout] Wait for submitted gate feedback
34
37
  fabrika builder ensure-daemon Start the daemon if it is not running
38
+ fabrika builder flows review Write the flows gate view: the route map from the flow files
39
+ fabrika builder design review Write the design checkpoint view: overrides, contrast, routes
35
40
  fabrika builder induce [--force] Derive issues from opice skeleton metadata
36
41
  fabrika builder build [--issue <ID>] [--assisted] Run the assisted per-issue build driver
42
+ fabrika builder build done <ID> [--verify <cmd>] Run the issue's check; record it as done only when green
43
+ A design checkpoint takes [--waive-contrast] instead
44
+ fabrika builder build block <ID> --reason <text> Record an issue as blocked
45
+ fabrika builder build status | review Print the board | write the build gate view from it
37
46
 
38
47
  Environment:
39
48
  FABRIKA_PORT Daemon port (default 19410)
@@ -46,7 +55,7 @@ export async function runBuilderCli(argv: readonly string[]): Promise<number> {
46
55
  return await dispatchBuilderCli(argv)
47
56
  } catch (error) {
48
57
  console.error(
49
- error instanceof BuilderCliError
58
+ error instanceof BuilderCliError || error instanceof InvalidApprovalsError
50
59
  ? error.message
51
60
  : 'Builder command failed. Check arguments, .fabrika/config.json, and the local dashboard; use --help for usage.',
52
61
  )
@@ -80,6 +89,10 @@ async function dispatchBuilderCli(argv: readonly string[]): Promise<number> {
80
89
  return cmdGate(rest)
81
90
  case 'ensure-daemon':
82
91
  return cmdEnsureDaemon(rest)
92
+ case 'flows':
93
+ return cmdFlows(rest)
94
+ case 'design':
95
+ return cmdDesign(rest)
83
96
  case 'induce':
84
97
  return cmdInduce(rest)
85
98
  case 'build':
@@ -0,0 +1,66 @@
1
+ import { GATE_APPROVE, GATE_CHANGES, GATE_VERDICT_ID, type GateVerdict } from '../../shared/gate'
2
+ import type { BuildBoard, BuildEvidence } from './build-status'
3
+ import type { Issue } from './issues'
4
+
5
+ export const BUILD_REVIEW_PATH = '.fabrika/build/review.jsx'
6
+
7
+ /**
8
+ * The build gate's view, generated from the recorded checks so the reviewer sees what ran, not what an agent reported.
9
+ * Every value from the repository reaches the view as a string literal whose characters outside a small safe set are
10
+ * `\uXXXX` escapes: the canvas compiler runs regex passes over the raw source, string contents included.
11
+ */
12
+ export function renderBuildReview(issues: Issue[], board: BuildBoard, now: Date): string {
13
+ const rows = issues.map((issue) => {
14
+ const rec = board[issue.id]
15
+ const status = rec?.status === 'done' ? 'done' : rec?.status === 'blocked' ? 'blocked' : 'not built'
16
+ return [issue.id, issue.goal, status, rec?.evidence ? describeEvidence(rec.evidence) : 'no recorded check']
17
+ })
18
+ const blocked = issues.flatMap((issue) => {
19
+ const rec = board[issue.id]
20
+ return rec?.status === 'blocked' ? [[issue.id, rec.reason ?? '(no reason given)']] : []
21
+ })
22
+ const done = rows.filter((row) => row[2] === 'done').length
23
+
24
+ const lines = [
25
+ `<Section title={${literal(`Build review — ${done}/${issues.length} issues done`)}}>`,
26
+ `\t<Note>{${literal(note(now))}}</Note>`,
27
+ `\t<Table headers={${literal(['Issue', 'Goal', 'Status', 'Check'])}} rows={${literal(rows)}} />`,
28
+ ]
29
+ if (blocked.length > 0) {
30
+ lines.push(`\t<Table headers={${literal(['Blocked issue', 'Reason'])}} rows={${literal(blocked)}} />`)
31
+ }
32
+ lines.push(
33
+ `\t<UserInput id="build-note" label="Notes for the blocked or unchecked issues?" placeholder="write here…" multiline />`,
34
+ `\t<Choice id="${GATE_VERDICT_ID}" label="Verdict" required options={['${GATE_APPROVE}', '${GATE_CHANGES}']} />`,
35
+ '</Section>',
36
+ )
37
+ return lines.join('\n') + '\n'
38
+ }
39
+
40
+ const VERDICT_TEXT: Record<GateVerdict, string> = { approve: 'approved', changes: 'changes requested', none: 'no verdict' }
41
+
42
+ export function describeEvidence(evidence: BuildEvidence): string {
43
+ const commit = `${evidence.commit === null ? 'no commit' : `at ${evidence.commit.slice(0, 7)}`}${evidence.dirty ? ' with uncommitted changes' : ''}`
44
+ const result = evidence.verdict === undefined
45
+ ? `exit ${evidence.exitCode} · ${(evidence.durationMs / 1000).toFixed(1)} s`
46
+ : VERDICT_TEXT[evidence.verdict]
47
+ return `${evidence.command} · ${result} · ${commit} · ${evidence.at}`
48
+ }
49
+
50
+ function note(now: Date): string {
51
+ return `Generated by \`fabrika builder build review\` at ${now.toISOString()} from .fabrika/build/status.json. The builder ran each check itself; "uncommitted changes" means the commit alone does not reproduce the run.`
52
+ }
53
+
54
+ type Literal = string | readonly Literal[]
55
+
56
+ const SAFE_CHAR = /^[A-Za-z0-9 .,:_/-]$/
57
+
58
+ export function literal(value: Literal): string {
59
+ if (typeof value !== 'string') return `[${value.map(literal).join(', ')}]`
60
+ let out = '"'
61
+ for (let i = 0; i < value.length; i++) {
62
+ const ch = value.charAt(i)
63
+ out += SAFE_CHAR.test(ch) ? ch : `\\u${value.charCodeAt(i).toString(16).padStart(4, '0')}`
64
+ }
65
+ return out + '"'
66
+ }
@@ -1,21 +1,58 @@
1
1
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
2
2
  import { dirname, join } from 'path'
3
3
  import { z } from 'zod'
4
+ import type { GateVerdict } from '../../shared/gate'
4
5
  import type { Issue } from './issues'
5
6
 
6
7
  export type IssueStatus = 'done' | 'blocked'
7
8
 
9
+ /** The check the builder itself ran before it recorded an issue as done. */
10
+ export interface BuildEvidence {
11
+ command: string
12
+ exitCode: number
13
+ durationMs: number
14
+ at: string
15
+ /** HEAD of the repository when the check ran; null outside git. */
16
+ commit: string | null
17
+ /** Uncommitted changes outside `.fabrika/` were present, so the commit alone does not reproduce the run. */
18
+ dirty: boolean
19
+ /** Set when the check was a review gate (the design checkpoint) rather than a command. */
20
+ verdict?: GateVerdict
21
+ }
22
+
8
23
  export interface BuildRecord {
9
24
  status: IssueStatus
10
25
  reason?: string
11
26
  at: string
27
+ evidence?: BuildEvidence
12
28
  }
13
29
 
14
30
  export type BuildBoard = Record<string, BuildRecord>
15
31
 
32
+ const buildEvidenceSchema = z.object({
33
+ command: z.string(),
34
+ exitCode: z.number().int(),
35
+ durationMs: z.number().nonnegative(),
36
+ at: z.string(),
37
+ commit: z.string().nullable(),
38
+ dirty: z.boolean(),
39
+ verdict: z.enum(['approve', 'changes', 'none']).optional().catch(undefined),
40
+ }).transform(({ verdict, ...evidence }) => ({ ...evidence, ...(verdict === undefined ? {} : { verdict }) }))
41
+
42
+ // A record written before evidence existed keeps its status and reads as "no recorded check".
16
43
  const buildBoardSchema = z.record(
17
- z.object({ status: z.enum(['done', 'blocked']), at: z.string(), reason: z.string().optional() })
18
- .transform(({ status, at, reason }) => ({ status, at, ...(reason === undefined ? {} : { reason }) })),
44
+ z.object({
45
+ status: z.enum(['done', 'blocked']),
46
+ at: z.string(),
47
+ reason: z.string().optional(),
48
+ evidence: buildEvidenceSchema.optional().catch(undefined),
49
+ })
50
+ .transform(({ status, at, reason, evidence }) => ({
51
+ status,
52
+ at,
53
+ ...(reason === undefined ? {} : { reason }),
54
+ ...(evidence === undefined ? {} : { evidence }),
55
+ })),
19
56
  )
20
57
 
21
58
  function parseBoard(value: unknown): BuildBoard | null {
@@ -50,9 +87,10 @@ export function record(
50
87
  status: IssueStatus,
51
88
  reason: string | undefined,
52
89
  at: string,
90
+ evidence?: BuildEvidence,
53
91
  ): BuildBoard {
54
92
  const board = readBoard(fabrikaDir)
55
- board[id] = { status, ...(reason ? { reason } : {}), at }
93
+ board[id] = { status, ...(reason ? { reason } : {}), at, ...(evidence ? { evidence } : {}) }
56
94
  writeBoard(fabrikaDir, board)
57
95
  return board
58
96
  }
@@ -1,4 +1,4 @@
1
- import { existsSync, statSync } from 'fs'
1
+ import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
2
2
  import { dirname, join, resolve } from 'path'
3
3
  import { fileURLToPath } from 'url'
4
4
 
@@ -12,27 +12,59 @@ export function resolveCatalogRoot(): string | null {
12
12
  return null
13
13
  }
14
14
 
15
+ /** The project profile a new project gets; `zerops-app` is the paved road the builder connects and deploys. */
16
+ export const DEFAULT_PROFILE = 'zerops-app'
17
+
18
+ /** `unsupported`: a preset kept for reference that leaves the paved road (no contract, proxy, kit or checker). */
19
+ export type StackSupport = 'supported' | 'unsupported'
20
+
15
21
  export interface StackPointer {
16
22
  profile: string
17
23
  root: string
18
24
  stackFile: string
19
25
  stackFileExists: boolean
20
26
  decisionsDir: string
27
+ /** Null when the preset file does not exist. */
28
+ support: StackSupport | null
21
29
  }
22
30
 
23
31
  export function resolveStackPointer(profile: string): StackPointer | null {
24
32
  const root = resolveCatalogRoot()
25
33
  if (!root) return null
26
34
  const stackFile = join(root, 'stacks', `${profile}.md`)
35
+ const stackFileExists = existsSync(stackFile) && statSync(stackFile).isFile()
27
36
  return {
28
37
  profile,
29
38
  root,
30
39
  stackFile,
31
- stackFileExists: existsSync(stackFile) && statSync(stackFile).isFile(),
40
+ stackFileExists,
32
41
  decisionsDir: join(root, 'decisions'),
42
+ support: stackFileExists ? stackSupport(readFileSync(stackFile, 'utf8')) : null,
33
43
  }
34
44
  }
35
45
 
46
+ /** The ids of the presets the builder supports, for pointing away from an unsupported one. */
47
+ export function supportedProfiles(): string[] {
48
+ const root = resolveCatalogRoot()
49
+ if (!root) return []
50
+ return readdirSync(join(root, 'stacks'))
51
+ .filter((name) => name.endsWith('.md') && name !== 'README.md')
52
+ .filter((name) => stackSupport(readFileSync(join(root, 'stacks', name), 'utf8')) === 'supported')
53
+ .map((name) => name.slice(0, -'.md'.length))
54
+ .sort()
55
+ }
56
+
57
+ export function unsupportedProfileNote(profile: string): string {
58
+ return `the "${profile}" preset is unsupported: it leaves the paved road (contract, proxy, @fabrika/ui, @fabrika/db, fabrika-check). `
59
+ + `Supported presets: ${supportedProfiles().join(', ')}.`
60
+ }
61
+
62
+ // A preset that does not say it is supported is treated as unsupported.
63
+ function stackSupport(source: string): StackSupport {
64
+ const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(source)?.[1] ?? ''
65
+ return /^support:\s*(["']?)supported\1\s*$/m.test(frontmatter) ? 'supported' : 'unsupported'
66
+ }
67
+
36
68
  function isDir(p: string): boolean {
37
69
  try {
38
70
  return statSync(p).isDirectory()
@@ -1,9 +1,12 @@
1
1
  import { parseArgs } from 'util'
2
- import { PHASE_COUNT, phaseById, phaseIndex, PHASES } from '../../../shared/phases'
2
+ import { readApprovals, writeApprovals } from '../../../shared/approvals'
3
+ import { isNonEmptyFile, matchGlob, phaseInputs, producesSatisfied } from '../../../shared/derive'
4
+ import { GATE_CHANGES } from '../../../shared/gate'
5
+ import { PHASE_COUNT, phaseById, type PhaseId, phaseIndex, PHASES } from '../../../shared/phases'
3
6
  import { resolveContext } from '../context'
4
- import { consumeFeedback } from '../daemon-client'
7
+ import { consumeGate } from '../daemon-client'
5
8
  import { isDaemonRunning } from '../daemon-lifecycle'
6
- import { isNonEmptyFile, matchGlob, producesSatisfied } from '../derive'
9
+ import { skeletonRouteWarnings } from '../flows'
7
10
  import { resolvePhaseState } from '../phase-state'
8
11
 
9
12
  export async function cmdAdvance(argv: string[]): Promise<number> {
@@ -38,6 +41,11 @@ export async function cmdAdvance(argv: string[]): Promise<number> {
38
41
  }
39
42
  }
40
43
 
44
+ let verdictWarning: string | null = null
45
+ let reviewedRevision: number | undefined
46
+ const reopen = `${phase.gateViewCommand ? `${phase.gateViewCommand} && ` : ''}fabrika builder gate open ${phase.id} --view ${
47
+ phase.gateView ?? phase.id + '.jsx'
48
+ } && fabrika builder gate wait`
41
49
  if (phase.gate && !values.force) {
42
50
  const daemonUp = await isDaemonRunning()
43
51
  if (!daemonUp) {
@@ -46,22 +54,41 @@ export async function cmdAdvance(argv: string[]): Promise<number> {
46
54
  + `Open the gate + submit feedback, or pass --force.`,
47
55
  )
48
56
  } else {
49
- const feedback = await consumeFeedback(ctx.sessionId)
50
- if (feedback === null) {
57
+ const review = await consumeGate(ctx.sessionId, phase.id)
58
+ const approved = readApprovals(ctx.repoRoot)?.[phase.id]?.revision
59
+ if (review === null) {
51
60
  problems.push(
52
61
  `gate "${phase.id}" has no submitted feedback to consume. `
53
- + `Run: fabrika builder gate open ${phase.id} --view ${phase.gateView ?? phase.id + '.jsx'} && fabrika builder gate wait`,
62
+ + `Run: ${reopen}`,
54
63
  )
64
+ } else if (approved !== undefined && review.revision <= approved) {
65
+ // The phase is current again because its files changed; the review it was approved on predates them.
66
+ problems.push(`gate "${phase.id}" was approved at revision ${review.revision}, before its files changed. Re-open it for a new review: ${reopen}`)
67
+ } else {
68
+ reviewedRevision = review.revision
69
+ if (review.verdict !== 'approve') {
70
+ // Gates are advisory: a person may move on over requested changes, but never silently.
71
+ verdictWarning = review.verdict === 'changes'
72
+ ? `gate "${phase.id}" was answered "${GATE_CHANGES}"; advancing anyway (gates are advisory). Address the requested changes or re-open the gate.`
73
+ : `gate "${phase.id}" was submitted without a verdict; advancing anyway (gates are advisory).`
74
+ }
55
75
  }
56
76
  }
57
77
  }
58
78
 
79
+ if (verdictWarning) console.error(`[fabrika] warning: ${verdictWarning}`)
80
+ if (phaseIndex(phase.id) >= phaseIndex('skeletons')) {
81
+ for (const warning of skeletonRouteWarnings(ctx.repoRoot)) console.error(`[fabrika] warning: ${warning}`)
82
+ }
83
+
59
84
  if (problems.length > 0) {
60
85
  console.error(`[fabrika] cannot advance from phase ${phase.number}/${PHASE_COUNT} (${phase.id}):`)
61
86
  for (const p of problems) console.error(` - ${p}`)
62
87
  return 1
63
88
  }
64
89
 
90
+ recordApproval(ctx.repoRoot, phase.id, values.force, reviewedRevision)
91
+
65
92
  const idx = phaseIndex(phase.id)
66
93
  const next = idx + 1 < PHASES.length ? PHASES[idx + 1] : null
67
94
  if (next) {
@@ -72,3 +99,18 @@ export async function cmdAdvance(argv: string[]): Promise<number> {
72
99
  }
73
100
  return 0
74
101
  }
102
+
103
+ /** Approves the gated phase over the inputs it reads now. */
104
+ function recordApproval(repoRoot: string, current: PhaseId, waived: boolean, revision: number | undefined): void {
105
+ const approvals = { ...readApprovals(repoRoot) }
106
+ const phase = phaseById(current)
107
+ if (phase.gate) {
108
+ approvals[current] = {
109
+ at: new Date().toISOString(),
110
+ inputs: phaseInputs(repoRoot, phase),
111
+ ...(waived ? { waived: true } : {}),
112
+ ...(revision !== undefined ? { revision } : {}),
113
+ }
114
+ }
115
+ writeApprovals(repoRoot, approvals)
116
+ }